<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>Reference</title>
    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>Duplex</h1>

<ul>
  <li><a href="../index.html">Index</a></li>
</ul>

<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
</ul>


<h2>Modules</h2>
<ul class="$(kind=='Topics' and '' or 'nowrap'">
  <li><a href="../modules/Duplex.Application.html">Duplex.Application</a></li>
  <li><a href="../modules/Duplex.Applications.Effect.html">Duplex.Applications.Effect</a></li>
  <li><a href="../modules/Duplex.Applications.GridPie.html">Duplex.Applications.GridPie</a></li>
  <li><a href="../modules/Duplex.Applications.Hydra.html">Duplex.Applications.Hydra</a></li>
  <li><a href="../modules/Duplex.Applications.Instrument.html">Duplex.Applications.Instrument</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.GridLayout.html">Duplex.Applications.Keyboard.GridLayout</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.Layouts.HarmonicLayout.html">Duplex.Applications.Keyboard.Layouts.HarmonicLayout</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.Layouts.IsomorphicLayout.html">Duplex.Applications.Keyboard.Layouts.IsomorphicLayout</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.Layouts.PianoLayout.html">Duplex.Applications.Keyboard.Layouts.PianoLayout</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.html">Duplex.Applications.Keyboard</a></li>
  <li><a href="../modules/Duplex.Applications.Matrix.html">Duplex.Applications.Matrix</a></li>
  <li><a href="../modules/Duplex.Applications.Metronome.html">Duplex.Applications.Metronome</a></li>
  <li><a href="../modules/Duplex.Applications.MidiActions.Bindings.html">Duplex.Applications.MidiActions.Bindings</a></li>
  <li><a href="../modules/Duplex.Applications.MidiActions.html">Duplex.Applications.MidiActions</a></li>
  <li><a href="../modules/Duplex.Applications.Mixer.html">Duplex.Applications.Mixer</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.Mlrx_group.html">Duplex.Applications.Mlrx.Mlrx_group</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.Mlrx_note.html">Duplex.Applications.Mlrx.Mlrx_note</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.Mlrx_pos.html">Duplex.Applications.Mlrx.Mlrx_pos</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.Mlrx_track.html">Duplex.Applications.Mlrx.Mlrx_track</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.html">Duplex.Applications.Mlrx</a></li>
  <li><a href="../modules/Duplex.Applications.Navigator.html">Duplex.Applications.Navigator</a></li>
  <li><a href="../modules/Duplex.Applications.NotesOnWheels.html">Duplex.Applications.NotesOnWheels</a></li>
  <li><a href="../modules/Duplex.Applications.PatternCursor.html">Duplex.Applications.PatternCursor</a></li>
  <li><a href="../modules/Duplex.Applications.PatternSequence.html">Duplex.Applications.PatternSequence</a></li>
  <li><a href="../modules/Duplex.Applications.Recorder.html">Duplex.Applications.Recorder</a></li>
  <li><a href="../modules/Duplex.Applications.Repeater.html">Duplex.Applications.Repeater</a></li>
  <li><a href="../modules/Duplex.Applications.Rotate.html">Duplex.Applications.Rotate</a></li>
  <li><a href="../modules/Duplex.Applications.StepSequencer.html">Duplex.Applications.StepSequencer</a></li>
  <li><a href="../modules/Duplex.Applications.SwitchConfiguration.html">Duplex.Applications.SwitchConfiguration</a></li>
  <li><a href="../modules/Duplex.Applications.TestPad.html">Duplex.Applications.TestPad</a></li>
  <li><a href="../modules/Duplex.Applications.TrackSelector.html">Duplex.Applications.TrackSelector</a></li>
  <li><a href="../modules/Duplex.Applications.Transport.html">Duplex.Applications.Transport</a></li>
  <li><a href="../modules/Duplex.Applications.UIButtonTest.html">Duplex.Applications.UIButtonTest</a></li>
  <li><a href="../modules/Duplex.Applications.XYPad.html">Duplex.Applications.XYPad</a></li>
  <li><a href="../modules/Duplex.Automation.html">Duplex.Automation</a></li>
  <li><a href="../modules/Duplex.Browser.html">Duplex.Browser</a></li>
  <li><a href="../modules/Duplex.BrowserProcess.html">Duplex.BrowserProcess</a></li>
  <li><a href="../modules/Duplex.Canvas.html">Duplex.Canvas</a></li>
  <li><a href="../modules/Duplex.CanvasPoint.html">Duplex.CanvasPoint</a></li>
  <li><a href="../modules/Duplex.ControlMap.html">Duplex.ControlMap</a></li>
  <li><a href="../modules/Duplex.Device.html">Duplex.Device</a></li>
  <li><a href="../modules/Duplex.Display.html">Duplex.Display</a></li>
  <li><a href="../modules/Duplex.Globals.html">Duplex.Globals</a></li>
  <li><a href="../modules/Duplex.Message.html">Duplex.Message</a></li>
  <li><a href="../modules/Duplex.MessageStream.html">Duplex.MessageStream</a></li>
  <li><a href="../modules/Duplex.MidiDevice.html">Duplex.MidiDevice</a></li>
  <li><a href="../modules/Duplex.OscClient.html">Duplex.OscClient</a></li>
  <li><a href="../modules/Duplex.OscDevice.html">Duplex.OscDevice</a></li>
  <li><a href="../modules/Duplex.OscVoiceMgr.html">Duplex.OscVoiceMgr</a></li>
  <li><a href="../modules/Duplex.Preferences.html">Duplex.Preferences</a></li>
  <li><a href="../modules/Duplex.ProcessSlicer.html">Duplex.ProcessSlicer</a></li>
  <li><a href="../modules/Duplex.RoamingDSP.html">Duplex.RoamingDSP</a></li>
  <li><a href="../modules/Duplex.Scheduler.html">Duplex.Scheduler</a></li>
  <li><a href="../modules/Duplex.StateController.html">Duplex.StateController</a></li>
  <li><a href="../modules/Duplex.UIButton.html">Duplex.UIButton</a></li>
  <li><strong>Duplex.UIButtonStrip</strong></li>
  <li><a href="../modules/Duplex.UIComponent.html">Duplex.UIComponent</a></li>
  <li><a href="../modules/Duplex.UIKey.html">Duplex.UIKey</a></li>
  <li><a href="../modules/Duplex.UIKeyPressure.html">Duplex.UIKeyPressure</a></li>
  <li><a href="../modules/Duplex.UILabel.html">Duplex.UILabel</a></li>
  <li><a href="../modules/Duplex.UIPad.html">Duplex.UIPad</a></li>
  <li><a href="../modules/Duplex.UIPitchBend.html">Duplex.UIPitchBend</a></li>
  <li><a href="../modules/Duplex.UISlider.html">Duplex.UISlider</a></li>
  <li><a href="../modules/Duplex.UISpinner.html">Duplex.UISpinner</a></li>
  <li><a href="../modules/Duplex.WidgetHooks.html">Duplex.WidgetHooks</a></li>
  <li><a href="../modules/Duplex.WidgetKeyboard.html">Duplex.WidgetKeyboard</a></li>
  <li><a href="../modules/Duplex.html">Duplex</a></li>
  <li><a href="../modules/main.html">main</a></li>
</ul>

</div>

<div id="content">

<h1>Module <code>Duplex.UIButtonStrip</code></h1>
<p>The UIButtonStrip is an array of buttons that control an active index/range,
especially useful for controlling a sequence with an a looped region.</p>
<p>
<p> </p>

<p>In addition to the basic set<em>range() and set</em>index() methods, there's two
additional methods, start/stop_blink(), which are used by the Matrix app
to display that a pattern has been scheduled.</p>

<h3>Usage</h3>

<p>This control has a number of interaction modes:</p>

<ol>
    <li><p>MODE_NORMAL - set range/index using button combinations </p>

    <p>In this mode, you set the index by pressing a button and releasing it,
    or set the range by pressing multiple buttons at the same time, and then
    releasing either. </p>

    <p>To toggle the range on/off, you press and hold a button for a moment,
    until the "button_held" event is triggered - this will toggle the range
    on/off (note that when turned on in this way, it's length is always one,
    as this length is otherwise unobtainable).</p>

    <p>Events</p>
    <ul>
        <li>on<em>index</em>change</li>
        <li>on<em>range</em>change</li>
    </ul>

    <p>Note: it is possible to return "false" to leave the index/range unchanged</p>

    <p>Supported input methods</p>
    <ul>
        <li>"button"</li>
    </ul></li>
    <li><p>MODE_INDEX - togglebutton compatible mode, only index can be set</p>

    <p>Events</p>
    <ul>
        <li>on<em>index</em>change</li>
    </ul>

    <p>Note: it is possible to return "false" to leave the index unchanged</p>

    <p>Supported input methods</p>
    <ul>
        <li>"button"</li>
        <li>"togglebutton"</li>
    </ul></li>
    <li><p>MODE_BASIC - free mode, supply your own logic</p></li>
</ol>

<p>  It's up to you to decide what happens when events are received</p>

<pre><code>Events
- on_press(idx)
- on_release(idx)*
- on_hold(idx)*

* "togglebutton" not supported for this type of event

Supported input methods
- "button"
- "togglebutton"
</code></pre>


<h3>Display logic</h3>

<p>For color displays, it's possible to differentiate
between the index and range</p>

<pre><code>[ ] = Background
[x] = Selected index
[o] = Range

[x][o][o][o][ ][ ] &lt;- Index set to 1, range set to 1,4
[o][o][x][o][ ][ ] &lt;- Index set to 3, range set to 1,4
[o][o][o][o][ ][x] &lt;- Index set to 6, range set to 1,4

For monochromatic devices / LED buttons, if the "index" color
is identical to the "range" color, the draw() method will use
an alternative/inverted color scheme:

[ ]     = Background
[x]/[ ] = Selected index
[x]     = Range

[ ][x][x][x][ ][ ] &lt;- Index set to 1, range set to 1,4
[x][x][ ][x][ ][ ] &lt;- Index set to 3, range set to 1,4
[ ][ ][x][ ][ ][ ] &lt;- Index set to 3, range set to 3,3
[x][x][x][x][ ][x] &lt;- Index set to 6, range set to 1,4
</code></pre>

</p>


<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#__init">__init (app, map)</a></td>
	<td class="summary">Initialize the UIButtonStrip class</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#do_press">do_press (msg)</a></td>
	<td class="summary">User pressed a button</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#do_release">do_release (msg)</a></td>
	<td class="summary">User released a button</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#do_hold">do_hold (msg)</a></td>
	<td class="summary">User held a button</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#draw">draw ()</a></td>
	<td class="summary">Update the appearance - inherited from UIComponent</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#set_index">set_index (idx, skip_event)</a></td>
	<td class="summary">Set the current index</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#get_index">get_index ()</a></td>
	<td class="summary">Get the current index</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#set_range">set_range (idx1, idx2, skip_event)</a></td>
	<td class="summary">Set the current range (swap values if needed, first should be lowest)</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#get_range">get_range ()</a></td>
	<td class="summary">Get the current range</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#_in_range">_in_range (idx)</a></td>
	<td class="summary">Check if provided index is within the current range</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#set_steps">set_steps (steps)</a></td>
	<td class="summary">Set the number of steps
  Will display the strip "stretched" along it's axis
  Sets the number of steps, in case the buttonstrip is larger than the number
  of steps it is controlling (like having 8 buttons to control 4 steps).</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#get_steps">get_steps ()</a></td>
	<td class="summary">Get the number of steps</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#start_blink">start_blink (idx)</a></td>
	<td class="summary">Start blinking behaviour for one of the buttons</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#pause_blink">pause_blink ()</a></td>
	<td class="summary">Pause blinking behaviour</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#stop_blink">stop_blink ()</a></td>
	<td class="summary">Stop blinking behaviour</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#_toggle_blink">_toggle_blink ()</a></td>
	<td class="summary">Toggle the control's blinking behaviour</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#set_orientation">set_orientation (value)</a></td>
	<td class="summary">Set the control's orientation</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#get_orientation">get_orientation ()</a></td>
	<td class="summary">Get the orientation</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#set_size">set_size (size)</a></td>
	<td class="summary">Override UIComponent with this method</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#add_listeners">add_listeners ()</a></td>
	<td class="summary">
<p>Add event listeners</p>
<pre><code>DEVICE_EVENT.BUTTON_PRESSED
DEVICE_EVENT.BUTTON_RELEASED
DEVICE_EVENT.BUTTON_HELD
</code></pre>
</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#remove_listeners">remove_listeners ()</a></td>
	<td class="summary">Remove previously attached event listeners</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#_determine_index_by_pos">_determine_index_by_pos (column, row)</a></td>
	<td class="summary">Determine the control's index by it's position</td>
	</tr>
</table>

<br/>
<br/>


    <h2><a name="Functions"></a>Functions</h2>
    <dl class="function">
    <dt>
    <a name = "__init"></a>
    <strong>__init (app, map)</strong>
    </dt>
    <dd>
    Initialize the UIButtonStrip class


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">app</span>
         (<a href="../modules/Duplex.Application.html#">Duplex.Application</a>)
        </li>
        <li><span class="parameter">map</span>
        [opt] (table) mapping properties
        </li>
    </ul>





</dd>
    <dt>
    <a name = "do_press"></a>
    <strong>do_press (msg)</strong>
    </dt>
    <dd>
    User pressed a button


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">msg</span>
         (<a href="../modules/Duplex.Message.html#">Duplex.Message</a>)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        self or nil if not handled
    </ol>




</dd>
    <dt>
    <a name = "do_release"></a>
    <strong>do_release (msg)</strong>
    </dt>
    <dd>
    User released a button


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">msg</span>
         (<a href="../modules/Duplex.Message.html#">Duplex.Message</a>)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        self or nil if not handled
    </ol>




</dd>
    <dt>
    <a name = "do_hold"></a>
    <strong>do_hold (msg)</strong>
    </dt>
    <dd>
    User held a button


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">msg</span>
         (<a href="../modules/Duplex.Message.html#">Duplex.Message</a>)
        </li>
    </ul>





</dd>
    <dt>
    <a name = "draw"></a>
    <strong>draw ()</strong>
    </dt>
    <dd>
    Update the appearance - inherited from UIComponent





    <h3>See also:</h3>
    <ul>
         <a href="../modules/Duplex.UIComponent.html#">Duplex.UIComponent</a>
    </ul>


</dd>
    <dt>
    <a name = "set_index"></a>
    <strong>set_index (idx, skip_event)</strong>
    </dt>
    <dd>
    Set the current index


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">idx</span>
         (int) the index to set
        </li>
        <li><span class="parameter">skip_event</span>
         (bool) if true, invoke the event handler
        </li>
    </ul>





</dd>
    <dt>
    <a name = "get_index"></a>
    <strong>get_index ()</strong>
    </dt>
    <dd>
    Get the current index



    <h3>Returns:</h3>
    <ol>

        int
    </ol>




</dd>
    <dt>
    <a name = "set_range"></a>
    <strong>set_range (idx1, idx2, skip_event)</strong>
    </dt>
    <dd>
    Set the current range (swap values if needed, first should be lowest)


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">idx1</span>
         (int) range 1
        </li>
        <li><span class="parameter">idx2</span>
         (int) range 2
        </li>
        <li><span class="parameter">skip_event</span>
         (bool) if true, invoke the event handler
        </li>
    </ul>





</dd>
    <dt>
    <a name = "get_range"></a>
    <strong>get_range ()</strong>
    </dt>
    <dd>
    Get the current range



    <h3>Returns:</h3>
    <ol>

        Table containing upper/lower index
    </ol>




</dd>
    <dt>
    <a name = "_in_range"></a>
    <strong>_in_range (idx)</strong>
    </dt>
    <dd>
    Check if provided index is within the current range


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">idx</span>



        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        bool
    </ol>




</dd>
    <dt>
    <a name = "set_steps"></a>
    <strong>set_steps (steps)</strong>
    </dt>
    <dd>
    Set the number of steps
  Will display the strip "stretched" along it's axis
  Sets the number of steps, in case the buttonstrip is larger than the number
  of steps it is controlling (like having 8 buttons to control 4 steps).


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">steps</span>
         (int)
        </li>
    </ul>





</dd>
    <dt>
    <a name = "get_steps"></a>
    <strong>get_steps ()</strong>
    </dt>
    <dd>
    Get the number of steps



    <h3>Returns:</h3>
    <ol>

        int
    </ol>




</dd>
    <dt>
    <a name = "start_blink"></a>
    <strong>start_blink (idx)</strong>
    </dt>
    <dd>
    Start blinking behaviour for one of the buttons


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">idx</span>
         (int) the button index
        </li>
    </ul>





</dd>
    <dt>
    <a name = "pause_blink"></a>
    <strong>pause_blink ()</strong>
    </dt>
    <dd>
    Pause blinking behaviour







</dd>
    <dt>
    <a name = "stop_blink"></a>
    <strong>stop_blink ()</strong>
    </dt>
    <dd>
    Stop blinking behaviour







</dd>
    <dt>
    <a name = "_toggle_blink"></a>
    <strong>_toggle_blink ()</strong>
    </dt>
    <dd>
    Toggle the control's blinking behaviour







</dd>
    <dt>
    <a name = "set_orientation"></a>
    <strong>set_orientation (value)</strong>
    </dt>
    <dd>
    Set the control's orientation


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">value</span>
         (<a href="../modules/Duplex.Globals.html#ORIENTATION">Duplex.Globals.ORIENTATION</a>)
        </li>
    </ul>





</dd>
    <dt>
    <a name = "get_orientation"></a>
    <strong>get_orientation ()</strong>
    </dt>
    <dd>
    Get the orientation



    <h3>Returns:</h3>
    <ol>

        <a href="../modules/Duplex.Globals.html#ORIENTATION">Duplex.Globals.ORIENTATION</a>
    </ol>




</dd>
    <dt>
    <a name = "set_size"></a>
    <strong>set_size (size)</strong>
    </dt>
    <dd>
    Override UIComponent with this method


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">size</span>
         (int) the size in units
        </li>
    </ul>



    <h3>See also:</h3>
    <ul>
         <a href="../modules/Duplex.UIComponent.html#">Duplex.UIComponent</a>
    </ul>


</dd>
    <dt>
    <a name = "add_listeners"></a>
    <strong>add_listeners ()</strong>
    </dt>
    <dd>

<p>Add event listeners</p>
<pre><code>DEVICE_EVENT.BUTTON_PRESSED
DEVICE_EVENT.BUTTON_RELEASED
DEVICE_EVENT.BUTTON_HELD
</code></pre>






    <h3>See also:</h3>
    <ul>
         <a href="../modules/Duplex.UIComponent.html#add_listeners">Duplex.UIComponent.add_listeners</a>
    </ul>


</dd>
    <dt>
    <a name = "remove_listeners"></a>
    <strong>remove_listeners ()</strong>
    </dt>
    <dd>
    Remove previously attached event listeners





    <h3>See also:</h3>
    <ul>
         <a href="../modules/Duplex.UIComponent.html#">Duplex.UIComponent</a>
    </ul>


</dd>
    <dt>
    <a name = "_determine_index_by_pos"></a>
    <strong>_determine_index_by_pos (column, row)</strong>
    </dt>
    <dd>
    Determine the control's index by it's position


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">column</span>
         (int)
        </li>
        <li><span class="parameter">row</span>
         (int)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        int
    </ol>




</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.2</a></i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
